play_1d

sound_pool object

This method will play a sound that can move around according to the listener and source positions on a 1d grid.

int play_1d(string filename, int listener_x, int sound_x, bool looping, bool persistent=false)

Parameters:
filename
The filename to play.
listener_x
The position of the listener on the grid.
sound_x
The position of the source object on the grid.
looping
A boolean specifying whether the sound should loop or not.
persistent
An optional boolean specifying whether the sound should be persistent or not, meaning whether or not it should be automatically cleaned up after playback has finished. If this argument is not given, false is the default which means that the sound does get cleaned up.

Return value:
Returns the slot where the sound is stored in the pool, -1 on error, or -2 if the sound is out of earshot.

Remarks:
This method is useful for playing sounds specific to the game objects and characters, for example monsters, health boosters, teleporters, etc.

A sound that is created with the persistent flag will not be cleaned up after it has finished playing, which otherwise is the default behavior. Instead, an explicit call must be made to destroy the sound. This is useful for non-looping sounds that you wish to be able to reliably manipulate with any of the functions that use slots to identify a particular sound. When set as persistent, a sound slot is guaranteed to stay valid regardless of playback status. This also means that you must be sure to destroy it when it is no longer in use, as that slot will otherwise be locked and not available for reuse by new sounds.

Example:

#include "sound_pool.bgt"

sound_pool sound_environment;
timer walk_timer;

int player_position;
int step;

const string sound_extension=".wav";

const int left=-1;
const int right=1;

const int boundary=200;

void main()
{
show_game_window("sound_pool test");
sound_environment.max_distance=70;
for(int counter=1; counter<15; counter++)
{
sound_environment.play_1d("sounds/sound"+counter+sound_extension, 0, random(0, boundary), true);
}
while(true)
{
check_input();
wait(5);
}
}

void check_input()
{
if((key_down(KEY_LMENU))&&(key_pressed(KEY_F4)))
{
exit();
}
if(key_down(KEY_LEFT))
{
walk(left);
}
if(key_down(KEY_RIGHT))
{
walk(right);
}
}

void walk(int direction)
{
if((direction<=left)&&(player_position<=0))
{
return;
}
if((direction>=right)&&(player_position>=boundary))
{
return;
}
if(walk_timer.elapsed<350)
{
return;
}
step++;
if(step>6)
{
step=1;
}
walk_timer.restart();
player_position+=direction;
sound_environment.play_stationary("sounds/steps/"+step+sound_extension, false);
sound_environment.update_listener_1d(player_position);
}